HOpenResFile

HOpenResFile
Header:	Resources.h		Carbon status:	Supported

Opens a file’s resource fork, when the FSpOpenResFile function is not available.

SInt16 HOpenResFile (
    SInt16 vRefNum, 
    SInt32 dirID, 
    ConstStr255Param fileName, 
    SInt8 permission
);

vRefNum: The volume reference number of the volume on which the file is located.
dirID: The directory ID of the directory where the file is located.
fileName: The name of the file whose resource fork is to be opened.
permission: A constant for one of the read/write permission combinations.

function result

The file reference number for the file. You can use this file reference number to refer to the file in other Resource Manager functions. The function also makes this file the current resource file. If the file’s resource fork is already open, the function returns the file reference number but does not make that file the current resource file. If the function fails to open the specified file’s resource fork (because there’s no file with the specified name or because there are permission problems), it returns –1 as the file reference number. Use the ResError function to determine what kind of error occurred.

Versions of system software before System 7 do not allow you to use this function to open a second access path, with write access, to a resource fork. In this case, the function returns the reference number already assigned to the file.0

DISCUSSION

The Resource Manager reads the resource map from the resource fork of the specified file into memory. It also reads into memory every resource whose resPreload attribute is set.

You don’t have to call this function to open the System file’s resource fork or an application file’s resource fork. These files are opened automatically when the system and the application start up, respectively. To get the file reference number for your application, call the CurResFile function after the application starts up and before you open the resource forks for any other files.

The HOpenResFile function checks that the information in the resource map is internally consistent. If it isn’t, ResError returns the result code mapReadErr. It’s possible to create multiple, unique, read-only access paths to a resource fork using HOpenResFile; however, you should avoid doing so, to prevent inconsistencies between multiple copies of the resource map. See the discussion of this issue in relation to FSpOpenResFile. The HOpenResFile function works the same way.

To open a resource fork just for block-level operations, such as copying files without reading the resource map into memory, use the File Manager function OpenRF.

If you want to open the resource fork for another application (or any resource fork other than your application’s that includes 'CODE' resources), you must bracket your calls to HOpenResFile with calls to the SetResLoad function with the load parameter set to FALSE and then to TRUE. You must also avoid making intersegment calls while the other application’s resource fork is open. The discussion of this issue in relation to FSpOpenResFile also applies to HOpenResFile.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.